Quality Gate per il Codice JavaScript: Padroneggiare la Configurazione degli Hook di Pre-commit

Nel mondo in continua evoluzione dello sviluppo software, mantenere un'alta qualità del codice è fondamentale. Un codice pulito, ben formattato e privo di bug non solo riduce i costi di manutenzione, ma favorisce anche la collaborazione e accelera i cicli di sviluppo. Una tecnica potente per imporre la qualità del codice è l'implementazione di quality gate utilizzando gli hook di pre-commit. Questo articolo fornisce una guida completa alla configurazione degli hook di pre-commit per progetti JavaScript, consentendoti di automatizzare i controlli di qualità del codice prima ancora che il codice raggiunga il tuo repository.

Cosa sono gli Hook di Pre-commit?

Gli hook di Git sono script che Git esegue prima o dopo eventi come commit, push e receive. Gli hook di pre-commit, in particolare, vengono eseguiti prima che un commit venga finalizzato. Offrono un'opportunità cruciale per ispezionare le modifiche che vengono committate e impedire i commit che non soddisfano gli standard di qualità predefiniti. Pensali come dei guardiani che impediscono al codice di bassa qualità di entrare nella tua codebase.

Perché Usare gli Hook di Pre-commit per la Qualità del Codice JavaScript?

• Rilevamento Precoce degli Errori: Gli hook di pre-commit intercettano i problemi di qualità del codice all'inizio del processo di sviluppo, impedendo loro di propagarsi ulteriormente. Questo è molto più efficiente che scoprire problemi durante le revisioni del codice o, peggio ancora, in produzione.
• Formattazione Automatica del Codice: Assicura uno stile di codice coerente in tutto il team e il progetto. La formattazione automatica previene i dibattiti stilistici e contribuisce a una codebase più leggibile.
• Riduzione del Carico di Revisione del Codice: Applicando automaticamente gli standard di codifica, gli hook di pre-commit riducono il carico sui revisori del codice, permettendo loro di concentrarsi su decisioni architetturali e logica complessa.
• Migliore Manutenibilità del Codice: Una codebase coerente e di alta qualità è più facile da mantenere ed evolvere nel tempo.
• Coerenza Forzata: Assicurano che tutto il codice sia conforme agli standard del progetto, indipendentemente dallo sviluppatore che lo ha scritto. Ciò è particolarmente importante nei team distribuiti che lavorano da luoghi diversi – diciamo, Londra, Tokyo e Buenos Aires – dove gli stili di codifica individuali potrebbero variare.

Strumenti Chiave per la Qualità del Codice JavaScript

Diversi strumenti sono comunemente usati in combinazione con gli hook di pre-commit per automatizzare i controlli di qualità del codice JavaScript:

• ESLint: Un potente linter JavaScript che identifica potenziali errori, impone stili di codifica e aiuta a migliorare la leggibilità del codice. Supporta una vasta gamma di regole ed è altamente configurabile.
• Prettier: Un formattatore di codice "opinionated" che formatta automaticamente il codice per aderire a uno stile coerente. Supporta JavaScript, TypeScript, JSX e molte altre lingue.
• Husky: Uno strumento che facilita la gestione degli hook di Git. Ti permette di definire script che verranno eseguiti in diverse fasi del flusso di lavoro di Git.
• lint-staged: Uno strumento che esegue linter e formattatori solo sui file in staging, accelerando significativamente il processo di pre-commit. Questo previene controlli non necessari su file non modificati.

Configurare gli Hook di Pre-commit: Una Guida Passo-Passo

Ecco una guida dettagliata su come impostare gli hook di pre-commit per il tuo progetto JavaScript usando Husky e lint-staged:

Passo 1: Installare le Dipendenze

Per prima cosa, installa i pacchetti necessari come dipendenze di sviluppo usando npm o yarn:

            npm install --save-dev husky lint-staged eslint prettier
            

              
                Copy
              
            
          

Oppure, usando yarn:

            yarn add --dev husky lint-staged eslint prettier
            

              
                Copy
              
            
          

Passo 2: Inizializzare Husky

Husky semplifica il processo di gestione degli hook di Git. Inizializzalo usando il seguente comando:

            npx husky install
            

              
                Copy
              
            
          

Questo creerà una directory `.husky` nel tuo progetto, che memorizzerà i tuoi hook di Git.

Passo 3: Configurare l'Hook di Pre-commit

Aggiungi un hook di pre-commit usando Husky:

            npx husky add .husky/pre-commit "npx lint-staged"
            

              
                Copy
              
            
          

Questo comando crea un file `pre-commit` nella directory `.husky` e vi aggiunge il comando `npx lint-staged`. Questo dice a Git di eseguire lint-staged prima di ogni commit.

Passo 4: Configurare lint-staged

lint-staged ti permette di eseguire linter e formattatori solo sui file in staging, il che accelera significativamente il processo di pre-commit. Crea un file `lint-staged.config.js` (o `lint-staged.config.mjs` per i moduli ES) nella radice del tuo progetto e configuralo come segue:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],
};
            

              
                Copy
              
            
          

Questa configurazione dice a lint-staged di eseguire ESLint e Prettier su tutti i file JavaScript e TypeScript in staging. Il flag `--fix` in ESLint corregge automaticamente tutti gli errori di linting che possono essere corretti automaticamente, e il flag `--write` in Prettier formatta i file e li sovrascrive con il codice formattato.

In alternativa, puoi definire la configurazione direttamente nel tuo file `package.json`:

            {
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}
            

              
                Copy
              
            
          

Passo 5: Configurare ESLint

Se non l'hai ancora fatto, configura ESLint per il tuo progetto. Puoi creare un file di configurazione ESLint usando il seguente comando:

            npx eslint --init
            

              
                Copy
              
            
          

Questo ti guiderà attraverso il processo di creazione di un file di configurazione ESLint (`.eslintrc.js`, `.eslintrc.json`, o `.eslintrc.yml`) in base ai requisiti del tuo progetto. Puoi scegliere tra una varietà di configurazioni predefinite o creare le tue regole personalizzate.

Esempio di `.eslintrc.js`:

            module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true
    },
    ecmaVersion: 12,
    sourceType: 'module'
  },
  plugins: [
    'react',
    '@typescript-eslint'
  ],
  rules: {
    'no-unused-vars': 'warn',
    'react/prop-types': 'off'
  }
};
            

              
                Copy
              
            
          

Questa configurazione estende le regole raccomandate di ESLint, le regole raccomandate di React, le regole raccomandate di TypeScript e si integra con Prettier. Disabilita anche la regola `react/prop-types` e imposta la regola `no-unused-vars` su un avviso.

Passo 6: Configurare Prettier

Configura Prettier creando un file `.prettierrc.js` (o `.prettierrc.json`, `.prettierrc.yml`, o `.prettierrc.toml`) nella radice del tuo progetto. Puoi personalizzare le opzioni di formattazione di Prettier per farle corrispondere alle linee guida di stile del tuo progetto.

Esempio di `.prettierrc.js`:

            module.exports = {
  semi: false,
  trailingComma: 'all',
  singleQuote: true,
  printWidth: 120,
  tabWidth: 2
};
            

              
                Copy
              
            
          

Questa configurazione imposta Prettier per usare apici singoli, nessun punto e virgola, virgole finali, una larghezza di stampa di 120 caratteri e una larghezza di tabulazione di 2 spazi.

In alternativa, puoi definire la configurazione di Prettier all'interno di `package.json`:

            {
  "prettier": {
    "semi": false,
    "trailingComma": "all",
    "singleQuote": true,
    "printWidth": 120,
    "tabWidth": 2
  }
}
            

              
                Copy
              
            
          

Passo 7: Testare la Configurazione

Per testare la configurazione, metti in staging alcune modifiche e prova a fare un commit. Ad esempio:

            git add .
            

              
                Copy
              
            
          

            git commit -m "Test hook di pre-commit"
            

              
                Copy
              
            
          

Se ci sono problemi di linting o formattazione, ESLint e Prettier li correggeranno automaticamente (se possibile) o segnaleranno errori. Se vengono segnalati errori, il commit verrà interrotto, permettendoti di risolvere i problemi prima di fare nuovamente il commit.

Opzioni di Configurazione Avanzate

Usare Linter e Formattatori Diversi

Puoi facilmente integrare altri linter e formattatori nella configurazione del tuo hook di pre-commit. Ad esempio, puoi usare Stylelint per il linting di file CSS o SASS:

            npm install --save-dev stylelint stylelint-config-standard
            

              
                Copy
              
            
          

Quindi, aggiorna il tuo file `lint-staged.config.js` per includere Stylelint:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],
  '*.{css,scss}': ['stylelint --fix'],
};
            

              
                Copy
              
            
          

Eseguire Test Prima del Commit

Puoi anche eseguire i tuoi test unitari come parte dell'hook di pre-commit. Questo aiuta a garantire che il tuo codice funzioni correttamente prima che venga committato. Supponendo che tu stia usando Jest:

            npm install --save-dev jest
            

              
                Copy
              
            
          

Aggiorna il tuo file `lint-staged.config.js` per includere il comando di test:

            module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write', 'jest --findRelatedTests'],
  '*.{css,scss}': ['stylelint --fix'],
};
            

              
                Copy
              
            
          

Il flag `--findRelatedTests` dice a Jest di eseguire solo i test correlati ai file modificati, il che accelera significativamente il processo.

Saltare gli Hook di Pre-commit

In alcuni casi, potresti voler saltare temporaneamente gli hook di pre-commit. Puoi farlo usando il flag `--no-verify` con il comando `git commit`:

            git commit --no-verify -m "Messaggio di commit"
            

              
                Copy
              
            
          

Tuttavia, è generalmente raccomandato di evitare di saltare gli hook a meno che non sia assolutamente necessario, poiché svolgono un ruolo cruciale nel mantenimento della qualità del codice.

Risoluzione dei Problemi Comuni

• Gli hook non vengono eseguiti: Assicurati che Husky sia installato e inizializzato correttamente, e che la directory `.husky` esista nella radice del tuo progetto. Verifica anche che il file `pre-commit` nella directory `.husky` sia eseguibile.
• Errori di linting non corretti: Assicurati che il flag `--fix` sia usato con ESLint, e che la tua configurazione ESLint sia impostata per correggere automaticamente certi tipi di errori.
• Prettier non formatta i file: Assicurati che il flag `--write` sia usato con Prettier, e che la tua configurazione Prettier sia impostata correttamente.
• Hook di pre-commit lenti: Usa lint-staged per eseguire linter e formattatori solo sui file in staging. Considera anche di ottimizzare le tue configurazioni di ESLint e Prettier per minimizzare il numero di regole e impostazioni che vengono controllate.
• Configurazioni in conflitto: Assicurati che le tue configurazioni di ESLint e Prettier non siano in conflitto tra loro. Se lo sono, potresti dover aggiustare una o entrambe le configurazioni per risolvere i conflitti. Considera l'uso di una configurazione condivisa come `eslint-config-prettier` e `eslint-plugin-prettier` per evitare conflitti.

Best Practice per gli Hook di Pre-commit

• Mantieni gli hook veloci: Gli hook lenti possono avere un impatto significativo sulla produttività degli sviluppatori. Usa lint-staged per elaborare solo i file in staging e ottimizza le configurazioni del tuo linter e formattatore.
• Fornisci messaggi di errore chiari: Quando un hook fallisce, fornisci messaggi di errore chiari e informativi per guidare gli sviluppatori su come risolvere i problemi.
• Automatizza il più possibile: Automatizza la formattazione del codice e il linting per minimizzare lo sforzo manuale e garantire la coerenza.
• Educa il tuo team: Assicurati che tutti i membri del team comprendano lo scopo degli hook di pre-commit e come usarli efficacemente.
• Usa una configurazione coerente: Mantieni una configurazione coerente per ESLint, Prettier e altri strumenti in tutto il tuo progetto. Questo aiuterà a garantire che tutto il codice sia formattato e analizzato allo stesso modo. Considera l'uso di un pacchetto di configurazione condiviso che può essere facilmente installato e aggiornato su più progetti.
• Testa i tuoi hook: Testa regolarmente i tuoi hook di pre-commit per assicurarti che funzionino correttamente e che non causino problemi imprevisti.

Considerazioni Globali

Quando si lavora in team distribuiti a livello globale, considera quanto segue:

• Versioni degli strumenti coerenti: Assicurati che tutti i membri del team utilizzino le stesse versioni di ESLint, Prettier, Husky e lint-staged. Questo può essere ottenuto specificando le versioni nel tuo file `package.json` e utilizzando un gestore di pacchetti come npm o yarn per installare le dipendenze.
• Compatibilità multipiattaforma: Testa i tuoi hook di pre-commit su diversi sistemi operativi (Windows, macOS, Linux) per assicurarti che funzionino correttamente su tutte le piattaforme. Usa strumenti e comandi multipiattaforma quando possibile.
• Differenze di fuso orario: Sii consapevole delle differenze di fuso orario quando comunichi con i membri del team riguardo ai problemi degli hook di pre-commit. Fornisci istruzioni ed esempi chiari per aiutarli a risolvere rapidamente i problemi.
• Supporto linguistico: Se il tuo progetto prevede di lavorare con più lingue, assicurati che i tuoi hook di pre-commit supportino tutte le lingue utilizzate nel progetto. Potrebbe essere necessario installare linter e formattatori aggiuntivi per ogni lingua.

Conclusione

Implementare gli hook di pre-commit è un modo efficace per imporre la qualità del codice, migliorare la collaborazione del team e ridurre i costi di manutenzione nei progetti JavaScript. Integrando strumenti come ESLint, Prettier, Husky e lint-staged, puoi automatizzare la formattazione del codice, il linting e i test, assicurando che solo codice di alta qualità venga committato nel tuo repository. Seguendo i passaggi descritti in questa guida, puoi impostare un robusto quality gate che ti aiuterà a costruire applicazioni JavaScript più pulite, manutenibili e affidabili. Adotta questa pratica ed eleva oggi stesso il flusso di lavoro di sviluppo del tuo team.